OpenDoc and SOMobjects

Inside Macintosh: OpenDoc Class Reference /: Preface - About This Book

OpenDoc and SOMobjects
OpenDoc objects follow the System Object Model(TM) (SOM(TM)), an object-oriented programming technology for building class libraries that support object binding at runtime. On the Mac OS platform, the OpenDoc class libraries are built with SOMobjects for Mac OS, Apple Computer's implementation of SOM.
The interfaces to SOM classes must be written in the CORBA Interface Definition Language (IDL), a programming-language-neutral syntax for creating interfaces. The interfaces are compiled separately from the implementations of the classes by the SOMobjects IDL compiler, which supports object-oriented programming languages such as C++ and procedural programming languages such as C.
Because OpenDoc uses SOMobjects and IDL, part editors and other OpenDoc classes that have been created with different compilers or in different programming languages can nevertheless communicate properly with one another. Furthermore, they can be independently revised and extended and still work together.

IDL Prototypes
Method prototypes in this book are presented in IDL syntax, which is similar to that of C and C++. IDL includes essentially the same character set, whitespace rules, comment styles, preprocessing capabilities, identifier-naming rules, and rules for literals. But there are a few notable differences in source-code appearance when declaring or calling methods of SOM-based objects:

In IDL method declarations, each parameter declaration is preceded by a directional attribute (in, out, or inout) that notes whether the parameter is used as an input, a result, or both.
The C++ interface to any method of a SOM object includes an extra initial parameter, the environment parameter (ev), used by all SOM methods to pass exceptions. See the chapter on OpenDoc runtime features in the OpenDoc Programmer's Guide for the MacOS for information on SOM exception handling.
The C interface to any SOM method includes another extra parameter (somSelf) before the environment parameter, specifying the object to which the method call is directed.

As an example of IDL syntax, here is the prototype for the AddProperty method of the ODStorageUnit class:
ODStorageUnit AddProperty(in ODPropertyName propertyName);
The directional attribute in indicates that the propertyName parameter is only passed into the method.
The SOMobjects IDL compiler converts IDL declarations into declarations and stub definitions in the selected implementation language. It adds any necessary parameters and converts out and inout parameters appropriately for the selected language. For example, out parameters may be implemented as pointers.

SOM Development
All OpenDoc objects are SOM objects, descended from the class SOMObject. Your subclass of ODPart must likewise be a SOM class. If you want other classes you define to be SOM classes, then you must write your interfaces in IDL, separate from your implementations. You must compile your interfaces with the SOMobjects IDL compiler, which can produce header files and stub implementation source files in the various programming languages supported by the SOMobjects IDL compiler. Options to the compiler specify which files to produce. You complete your development by writing your implementations into the stub implementation files and compiling them, along with the header files, using a standard compiler for your programming language.
For information on SOMobjects, see SOMobjects for Mac OS. For information on using the SOMobjects IDL compiler on the Mac OS platform, see the OpenDoc Cookbook for the Mac OS. For a more detailed description of the Interface Definition Language and instructions on programming with SOM, see SOMobjects Developer Toolkit Users Guide and SOMobjects Developer Toolkit Programmers Reference Manual from IBM.